%> @file readme.m
%> @brief This is a short README about how to use the code.
%> @author Mikhail V. Konnik
%> @date   10 December 2014.
%> 
%> In short, you need to run in MATLAB either of these files:
%> - a simple sensor model in test_photosensor_simple_model.m  file
%> - or an advanced model in test_photosensor_advanced_model.m  file
%> 
%> Each of them will run the function ccd_photosensor.m that is @ref ccdphotosensor "thoroughly documented".
%> The example will run the simulation of a 256x256 pixels CCD photosensor.
%> 
%> 
%> 
%> @mainpage High-level CCD/CMOS Sensor Simulator
%> This MATLAB code serves as an example of implementation of a high-level CCD/CMOS photosensor
%> model, which has been described in the article "High-level numerical simulations of noise in solid-state photosensors:  review and tutorial"
%> by Mikhail Konnik and James Welsh. The code was originally written and used for the Adaptive Optics simulations and study of
%> noise propagation in wavefront sensors, but can be used for many other applications involving light registration on CCD/CMOS
%> photosensors. The code is written as a series of functions (plain-old imperative style, no fluffy object-oriented stuff),
%> which are all contained inside the ccd_photosensor.m function, which takes the input optical field as an input and 
%> sequentially adds light and dark noises.
%> 
%> This code is intended to be an @i example implementation of the sensor model: for the article we used this very code, although
%> slightly modified (especially when we studied long-exposure dark noise). The code is documented using portions of the text from
%> the article, should be (hopefully) easy to follow and modify. 
%> 
%> @section runme Running the simulation
%> The whole simulation code is in the /sensors directory, while /help directory contains the documentation in HTML 
%> that is generated by Doxygen from the comments within the code. Two examples of sensors models are provided:
%> - a @b simple model, which is completely linear (no non-linearities), where all noise are basically Gaussian, 
%> and without source follower noise, is in the test_photosensor_simple_model.m file.
%> - an @b advanced model, which has V/V and V/e non-linearities, Wald/LogNormal noise, source follower and sense node noise 
%> sources and even ADC non-linearities (you can turn them all on or off), is in the test_photosensor_advanced_model.m file. 
%> In case the last sentence does not make any sense, use the simple model. 
%> 
%> The example test files will run the simulation of a 256x256 pixels CCD photosensor, triggering the ccd_photosensor.m file 
%> that actually performs the simulations.
%> 
%> 
%> @section howworks How does the model work?
%> This is described in the article mentioned above (you can also find it in Arxiv.org). Everything about the simulation
%> of the photosensor, all the parameters and noises (in photons, electrons, volts and DN) are stored inside the @b ccd structure.
%> Go to ccd_photosensor.m file for the details of the @ref ccdphotosensor "High-level photosensor model" being implemented.
%> 
%> In short, the model assumes the input of an optical field and converts it into \f$ W/m^2 \f$, giving the signal in photons 
%> stored in @b ccd.Signal_CCD_photons matrix. Then the noise (in electrons) is added to light signal and stored in @b ccd.light_signal matrix, 
%> while the dark noise is added to the b ccd.dark_signal matrix. 
%> The image in electrons is the obtained in @b ccd.Signal_CCD_electrons matrix by adding @b ccd.light_signal and @b ccd.dark_signal 
%> according to the parameters set by a user.
%> 
%> Then the signal in electrons is converted into Voltages, resulting in the @b ccd.Signal_CCD_voltage matrix. After that, 
%> we proceed to the Analogue-to-Digital converter (ADC) to finally convert into Digital Numbers (DN) according to
%> the number of bits set by user (usually 8, 12 or 16 bit). The final result is in the @b ccd.Signal_CCD_DN matrix, in digital numbers.
%> 
%> The illustration of the simulation process is provided below:
%> 
%> @image html camerascheme_vert.png
%> 
%> I hope that this model will be useful for somebody, or at least save someone's time.
%> The model can be (and should be) criticized, but this author would like to use a quote from
%> George E. P. Box, who was famous statistician, and who used to say that 
%> "essentially, all models are wrong, but some are useful".